{% extends "base.html" %}

{% block title %}API Documentation - Flask Blueprints Demo{% endblock %}

{% block content %}
<h2>API Documentation</h2>

<div class="row">
    <div class="col-md-8">
        <div class="alert alert-info">
            <strong>API Access:</strong> This documentation describes the available RESTful API endpoints. 
            All endpoints return JSON data and require proper authentication in a production environment.
        </div>
        
        <h3>Authentication</h3>
        <p>Most API endpoints require authentication using an API key. Include the key in the <code>Authorization</code> header:</p>
        <pre>Authorization: Bearer YOUR_API_KEY</pre>
        
        <h3>Base URL</h3>
        <p>All API endpoints are relative to the base URL:</p>
        <pre>{{ request.url_root }}api/</pre>
        
        <h3>Endpoints</h3>
        
        <div class="card mb-3">
            <div class="card-header">
                <h5>GET /api/users</h5>
            </div>
            <div class="card-body">
                <p><strong>Description:</strong> Retrieve a list of all users</p>
                <p><strong>Parameters:</strong> None</p>
                <p><strong>Response:</strong></p>
                <pre>{
  "users": [
    {
      "id": 1,
      "username": "alice",
      "email": "alice@example.com",
      "created_at": "2023-01-01T12:00:00Z"
    },
    {
      "id": 2,
      "username": "bob",
      "email": "bob@example.com",
      "created_at": "2023-01-02T12:00:00Z"
    }
  ]
}</pre>
            </div>
        </div>
        
        <div class="card mb-3">
            <div class="card-header">
                <h5>GET /api/users/&lt;id&gt;</h5>
            </div>
            <div class="card-body">
                <p><strong>Description:</strong> Retrieve information about a specific user</p>
                <p><strong>Parameters:</strong> User ID (integer)</p>
                <p><strong>Response:</strong></p>
                <pre>{
  "id": 1,
  "username": "alice",
  "email": "alice@example.com",
  "created_at": "2023-01-01T12:00:00Z",
  "posts": [
    {
      "id": 1,
      "title": "First Post",
      "created_at": "2023-01-01T13:00:00Z"
    }
  ]
}</pre>
            </div>
        </div>
        
        <div class="card mb-3">
            <div class="card-header">
                <h5>GET /api/posts</h5>
            </div>
            <div class="card-body">
                <p><strong>Description:</strong> Retrieve a list of all blog posts</p>
                <p><strong>Parameters:</strong> 
                    <ul>
                        <li><code>page</code> (optional): Page number for pagination (default: 1)</li>
                        <li><code>per_page</code> (optional): Number of posts per page (default: 10, max: 100)</li>
                    </ul>
                </p>
                <p><strong>Response:</strong></p>
                <pre>{
  "posts": [
    {
      "id": 1,
      "title": "First Post",
      "excerpt": "This is the first post...",
      "author": {
        "id": 1,
        "username": "alice"
      },
      "created_at": "2023-01-01T13:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "pages": 3,
    "per_page": 10,
    "total": 25
  }
}</pre>
            </div>
        </div>
    </div>
    
    <div class="col-md-4">
        <div class="card">
            <div class="card-header">
                <h5>API Information</h5>
            </div>
            <div class="card-body">
                <p><strong>Version:</strong> v1.0</p>
                <p><strong>Format:</strong> JSON</p>
                <p><strong>Rate Limit:</strong> 1000 requests/hour</p>
            </div>
        </div>
        
        <div class="card mt-3">
            <div class="card-header">
                <h5>Try the API</h5>
            </div>
            <div class="card-body">
                <p>Test the API endpoints directly:</p>
                <a href="{{ url_for('api.users') }}" class="btn btn-primary w-100 mb-2">List Users</a>
                <a href="{{ url_for('api.posts') }}" class="btn btn-primary w-100">List Posts</a>
            </div>
        </div>
        
        <div class="card mt-3">
            <div class="card-header">
                <h5>Error Handling</h5>
            </div>
            <div class="card-body">
                <p>API errors are returned with appropriate HTTP status codes:</p>
                <ul>
                    <li><code>400</code>: Bad Request</li>
                    <li><code>401</code>: Unauthorized</li>
                    <li><code>404</code>: Not Found</li>
                    <li><code>500</code>: Internal Server Error</li>
                </ul>
            </div>
        </div>
    </div>
</div>

<div class="mt-4">
    <a href="{{ url_for('main.index') }}" class="btn btn-secondary">Back to Home</a>
</div>
{% endblock %}